 Copyright (c) 2001, 2009, Oracle and/or its affiliates. All rights reserved. 


         Oracle Multimedia PL/SQL Web Toolkit Sample Application
         =======================================================


This file describes the steps required to build and run the Oracle Multimedia
PL/SQL Web Toolkit Photo Album sample application.  This sample application
is installed from the Oracle Database Examples media which is available 
for download from Oracle Technology Network.


Contents
========

    Requirements
    About the Sample Application
    Setup and Build the Sample Application
    Running the Sample Application
    Removing the Sample Application
    Known Issues





Requirements
============

Requirements for running the Oracle Multimedia PL/SQL Web Toolkit Photo 
Album sample application:

1) Server component:
   Oracle Database 11g Release 2 (11.2) with Oracle Multimedia, Oracle XML DB, 
   and Oracle Text installed. (Oracle Multimedia, Oracle XML DB and 
   Oracle Text are installed by default.) 

2) Client component: (choose one)

   - Oracle HTTP Server with PL/SQL Gateway (mod_plsql) installed.

     Oracle HTTP Server is distributed with Oracle Application Server 10g. It
     is also available as a separate download from Oracle Technology Network.

   - Oracle Embedded PL/SQL Gateway

     The embedded version of the PL/SQL gateway runs in the XML DB HTTP 
     Listener in the database. It provides the core features of mod_plsql 
     in the database but does not require the Oracle HTTP Server.     


About the Sample Application
============================

The Oracle Multimedia PL/SQL Web Toolkit Photo Album sample application is a 
sample PL/SQL application that demonstrates how to use the PL/SQL Tookit to 
upload, retrieve and process multimedia data stored using the Oracle 
Multimedia ORDImage data type. Users access the application to view the 
contents of the photo album, including thumbnail versions of each photo, 
to view the full-size version of any photo, and to upload new photos into 
the album. Metadata that is embedded within the image file is automatically 
extracted and represented in XML documents. These documents are schema based 
and are then stored in XMLType columns in the database.  The sample 
application also presents a form to collect metadata from the user and embeds 
the metadata into the binary image. The sample application shows how the 
metadata can be searched using full text search and as well as schema based 
search techniques.

The sample application contains the following files:
  README.txt     -- instructions for installing and using the application
  install.sql    -- application installation script
  remove.sql     -- application removal script
  photostab.sql  -- creates table and related schema objects
  photosidx.sql  -- creates indexes and related schema objects
  photospkg.sql  -- creates application code


Installing the sample application
=================================

1) Create the photo album tables, indexes and application. Grant EXECUTE on
   CTX_DDL to the sample application schema user.

   Choose a database schema for the photo album sample application.

   The Oracle Multimedia PL/SQL Web Toolkit Photo Album sample application 
   uses a database  sequence and the following table definition:

      Name                  Null?     Type
      --------------------  --------  ----------------------------
      ID                    NOT NULL  NUMBER PRIMARY KEY
      DESCRIPTION           NOT NULL  VARCHAR2(40)
      METAORDIMAGE                    XMLTYPE
      METAEXIF                        XMLTYPE
      METAIPTC                        XMLTYPE
      METAXMP                         XMLTYPE
      IMAGE                           ORDSYS.ORDIMAGE
      THUMB                           ORDSYS.ORDIMAGE
 
   The Oracle Multimedia PL/SQL Web Toolkit Photo Album Sample Application 
   uses the following document table definition, as prescribed by the PL/SQL 
   Gateway:

      Name                  Null?     Type
      --------------------  --------  ----------------------------
      NAME                  NOT NULL  VARCHAR2(256)
      MIME_TYPE                       VARCHAR2(128)
      DOC_SIZE                        NUMBER
      DAD_CHARSET                     VARCHAR2(128)
      LAST_UPDATED                    DATE
      CONTENT_TYPE                    VARCHAR2(128)
      BLOB_CONTENT                    BLOB

   The Oracle Multimedia PL/SQL Web Toolkit Photo Album Sample Application 
   creates an Oracle Text index to enable full text search on image metadata.
   The install script will GRANT EXECUTE on the CTX_DDL package to the 
   sample application schema user.

   Start SQL*Plus and connect to the database with the SYSTEM username
   and password

->  SQL> connect SYSTEM[@<SERVICE>]
    Enter password: <password>

    Install the application by executing the install.sql script.

->  SQL> @install.sql

    The script will prompt you for the database schema where the application
    will be installed:

       Enter schema to install Photo Album: 

    Type the name of the schema and press return. The script will install 
    the application. A logfile of the install session will be saved in the file
    install.log.

***
*** If you have installed Oracle Application Server 10g, or the Oracle 
*** HTTP Server standalone, then skip step 2 and proceed to step 3. 
*** If you wish to run the application using the Embedded PL/SQL Gateway 
*** of Oracle Database, then proceed  to step 2.
***

2) Create a Database Access Descriptor (DAD) to run the sample application:
   Use when configuring with Embedded PL/SQL Gateway for Oracle Database.

   This example configuration uses the HTTP Basic Authentication technique
   for authenticating web clients to the application. HTTP Basic Authentication
   sends usernames and passwords in clear text to the HTTP Server.

   For simplicity in demonstrating this feaure, this example does not perform 
   the password management techniques that a deployed system normally uses.
   In a production environment, follow the Oracle Database password managment
   guidelines. See Oracle Database Security Guide for password managment 
   guidelines and other security recommendations.

-> Using SQL*Plus, run the following block of code from an account with the 
   XDBADMIN role. First change the value of variable "pa_user" to the schema
   name where you have installed the application.

   ***** BEGIN CODE BLOCK
   declare
     -- Change schema name for your application.
     pa_user varchar2(30) := 'SCOTT'; 
   begin
     dbms_epg.create_dad('PA_DAD', '/photoalbum/*');
     dbms_epg.set_dad_attribute('PA_DAD', 'database-username', pa_user);
     dbms_epg.set_dad_attribute('PA_DAD', 'authentication-mode', 'Basic');
     dbms_epg.set_dad_attribute('PA_DAD', 'default-page', 
                                'PHOTO_ALBUM.VIEW_ALBUM');
     dbms_epg.set_dad_attribute('PA_DAD', 'document-table-name', 
                                'PHOTOS_UPLOAD');
     dbms_epg.set_dad_attribute('PA_DAD', 'request-validation-function',
                                'PHOTO_ALBUM.VALIDATE_REQUEST');
   end;
   /
   ***** END CODE BLOCK

-> Run the command 
   SQL> <ORACLE_HOME>/rdbms/admin/epgstat.sql 
   to verify the configuration for the Embedded PL/SQL Gateway.

***
*** If you completed step 2, then skip step 3 and proceed to "Running the.
*** Sample Application. If you have installed Oracle Application Server 10g,
*** or the Oracle HTTP Server, then proceed to step 3.
***

3) Create a Database Access Descriptor (DAD) to run the sample application:
   Use when configuring with Oracle HTTP Server.

-> Edit the DAD configuration file 

   For Oracle HTTP Server standalone 
     UNIX:    OHS_HOME/ohs/modplsql/conf/dads.conf
     Windows: OHS_HOME\ohs/modplsql\conf\dads.conf

   where OHS_HOME is the directory path for the root of the Oracle
   HTTP Server installation.

   For Oracle Application Server 10g
     UNIX:    OAS_HOME/Apache/modplsql/conf/dads.conf
     Windows: OAS_HOME\Apache/modplsql\conf\dads.conf

   where OAS_HOME is the directory path for the root of the Oracle Application 
   Server 10g installation.

   Add the following definition to the dads.conf file, replacing the strings
   <USER>, <PASSWORD>, <CONNECT_STRING> with the correct values for your
   installation. Note that the <USER> must be the same schema name that 
   you chose in step 1.

     <Location /photoalbum>
       SetHandler pls_handler
       Order deny,allow
       Allow from all
       AllowOverride None
       PlsqlDatabaseUsername          <USER>
       PlsqlDatabasePassword          <PASSWORD>
       PlsqlDatabaseConnectString     <CONNECT_STRING>
       PlsqlDefaultPage               PHOTO_ALBUM.VIEW_ALBUM
       PlsqlDocumentTablename         PHOTOS_UPLOAD
       PlsqlRequestValidationFunction PHOTO_ALBUM.VALIDATE_REQUEST
     </Location>

   The following is an example DAD for the SCOTT schema:

     <Location /photoalbum>
       SetHandler pls_handler
       Order deny,allow
       Allow from all
       AllowOverride None
       PlsqlDatabaseUsername          SCOTT
       PlsqlDatabasePassword          <password for SCOTT>
       PlsqlDatabaseConnectString     fastbox:1521:orcl ServiceNameFormat
       PlsqlDefaultPage               PHOTO_ALBUM.VIEW_ALBUM
       PlsqlDocumentTablename         PHOTOS_UPLOAD
       PlsqlRequestValidationFunction PHOTO_ALBUM.VALIDATE_REQUEST       
     </Location>

   Note that this example uses the ServiceNameFormat, HOST:PORT:SERVICE_NAME, 
   to define the database connect string. Other formats for defining the
   database connect string are: SIDFormat, TNSFormat and NetServiceNameFormat.
   The file OHS_HOME/ohs/modplsql/conf/dads.README explains how
   to use these other formats. It also documents DAD creation in general.

-> Save the edits to the file dads.conf.

-> Obfuscate the DAD password by running the "dadTool.pl" script located in
   OHS_HOME/ohs/modplsql/conf. For instructions on performing the
   obfuscation, please refer to OHS_HOME/ohs/modplsql/conf/dadTool.README

-> Restart the Oracle HTTP Server for the configuration to take effect.

Running the Sample Application
==============================

To use the sample application, enter the photo album URL into the location bar 
of your web browser. For example:

  http://<hostname>:<port>/photoalbum/

If you have configurated the application using the Embedded PL/SQL gateway,
then you will be prompted with a login dialog window. Enter the username and
password for the database schema where the application was installed.

When first invoked, the application displays any images that are currently
stored in the album. To upload a new photo, click on the "Upload photo"
link. Enter a description of the photo, and the name of the image file, 
then click the "Upload photo" button. The contents of the photo album are 
then displayed, along with the new photo. Click on a thumbnail image to view 
the full-size version of any photo. The application displays the text 
"[view image]" instead of a thumbnail image for images with formats that 
are not recognized by Oracle Multimedia. 

Removing the Sample Application
===============================

The sample application can be removed by running the deinstallation script 
remove.sql.  This script will remove schema objects and revoke privileges
that were created or granted by the installation in the sample application
user schema.

   Start SQL*Plus and connect to the database with the SYSTEM username
   and password

->  SQL> connect SYSTEM[@<SERVICE>]
    Enter password: <password>

    Remove the application by executing the remove.sql script.

->  SQL> @remove.sql

    The script will prompt you for the database schema where the application
    will be removed:

       Enter schema to remove Photo Album: 

    Type the name of the schema and press return. The script will remove
    the application. A logfile of the remove session will be saved in the file
    remove.log.

Known Issues
============
None.

=================
End of README.txt
